Inside Macintosh: Imaging With QuickDraw /: Chapter 2 - Basic QuickDraw

Summary of Basic QuickDraw

Pascal Summary

Data Types

TYPE  Point = 
      RECORD CASE Integer OF
         0: (v:ÊÊ       Integer;    {vertical coordinate}
             h:ÊÊ       Integer);   {horizontal coordinate}
         1: (vh:Ê       ARRAY[VHSelect] OF Integer);
      END;
Rect = 
      RECORD CASE Integer OF        {cases: 4 boundaries or 2 corners}
         0: (top:       Integer;    {upper boundary of rectangle}
             left:      Integer;    {left boundary of rectangle}
             bottom:    Integer;    {lower boundary of rectangle}
             right:     Integer);   {right boundary of rectangle}
         1: (topLeft:   Point;      {upper-left corner of rectangle}
             botRight:  Point);     {lower-right corner of rectangle}
      END;
RgnHandle = ^RgnPtr;
      RgnPtr =    ^Region;
      Region = 
      RECORD
         rgnSize: Integer; {size in bytes}
         rgnBBox: Rect;    {enclosing rectangle}
         {more data if not rectangular}
      END;
BitMap =
      RECORD
         baseAddr:   Ptr;     {pointer to bit image}
         rowBytes:   Integer; {row width}
         bounds:     Rect;    {boundary rectangle}
      END;
GrafPtr =      ^GrafPort;
      WindowPtr =    GrafPtr;
GrafPort =  {basic graphics port}
      RECORD
         device:     Integer;    {device-specific information}
         portBits:   BitMap;     {bitmap}
         portRect:   Rect;       {port rectangle}
         visRgn:     RgnHandle;  {visible region}
         clipRgn:    RgnHandle;  {clipping region}
         bkPat:      Pattern;    {background pattern}
         fillPat:    Pattern;    {fill pattern}
         pnLoc:      Point;      {pen location}
         pnSize:     Point;      {pen size}
         pnMode:     Integer;    {pattern mode}
         pnPat:      Pattern;    {pen pattern}
         pnVis:      Integer;    {pen visibility}
         txFont:     Integer;    {font number for text}
         txFace:     Style;      {text's font style}
         txMode:     Integer;    {source mode for text}
         txSize:     Integer;    {font size for text}
         spExtra:    Fixed;      {extra space}
         fgColor:    LongInt;    {foreground color}
         bkColor:    LongInt;    {background color}
         colrBit:    Integer;    {color bit}
         patStretch: Integer;    {used internally}
         picSave:    Handle;     {picture being saved, used internally}
         rgnSave:    Handle;     {region being saved, used internally}
         polySave:   Handle;     {polygon being saved, used internally}
         grafProcs:  QDProcsPtr; {low-level drawing routines}
      END;

Routines

Initializing QuickDraw

PROCEDURE InitGraf       (globalPtr: Ptr);

Opening and Closing Basic Graphics Ports

PROCEDURE OpenPort       (port:ÊGrafPtr);
PROCEDURE InitPort       (port: GrafPtr); 
PROCEDURE ClosePort      (port:ÊGrafPtr);

Saving and Restoring Graphics Ports

PROCEDURE GetPort        (VAR port: GrafPtr);
PROCEDURE SetPort        (port: GrafPtr);

Managing Bitmaps, Port Rectangles, and Clipping Regions

PROCEDURE ScrollRect     (r:ÊRect; dh,dv: Integer; updateRgn: RgnHandle);
PROCEDURE SetOrigin      (h,v: Integer);
PROCEDURE PortSize       (width,height:ÊInteger);
PROCEDURE MovePortTo     (leftGlobal,topGlobal:ÊInteger);
PROCEDURE GetClip        (rgn: RgnHandle);
PROCEDURE SetClip        (rgn: RgnHandle);
PROCEDURE ClipRect       (r: Rect);
FUNCTION BitMapToRegion  (region: RgnHandle; bMap: BitMap): OSErr;
PROCEDURE SetPortBits    (bm: BitMap);

Manipulating Points in Graphics Ports

PROCEDURE GlobalToLocal  (VAR pt: Point);
PROCEDURE LocalToGlobal  (VAR pt: Point);
PROCEDURE AddPt          (srcPt: Point; VAR dstPt:ÊPoint);
PROCEDURE SubPt          (srcPt:ÊPoint; VAR dstPt:ÊPoint);
FUNCTION DeltaPoint      (ptA: Point; ptB: Point): LongInt;
PROCEDURE SetPt          (VAR pt:ÊPoint; h,v:ÊInteger);
FUNCTION EqualPt         (pt1,pt2: Point): Boolean;
FUNCTION GetPixel        (h,v:ÊInteger):ÊBoolean;

C Summary

Data Types

struct Point {
      short v;    /* vertical coordinate */
      short h;    /* horizontal coordinate */
   };
struct Rect {
      short top;     /* upper boundary of rectangle */
      short left;    /* left boundary of rectangle */
      short bottom;  /* lower boundary of rectangle */
      short right;   /* right boundary of rectangle */
   };
struct Region {
      short rgnSize;          /* size in bytes */
      Rect  rgnBBox;          /* enclosing rectangle */
      /* more data if not rectangular */
   };
typedef struct Region Region;
typedef Region *RgnPtr, **RgnHandle;
struct BitMap {
      Ptr   baseAddr;         /* pointer to bit image */
      short rowBytes;         /* row width */
      Rect  bounds;           /* boundary rectangle */
   };
struct GrafPort {             /* basic graphics port */
      short       device;     /* device-specific information */
      BitMap      portBits;   /* bitmap */
      Rect        portRect;   /* port rectangle */
      RgnHandle   visRgn;     /* visible region */
      RgnHandle   clipRgn;    /* clipping region */
      Pattern     bkPat;      /* background pattern */
      Pattern     fillPat;    /* fill pattern */
      Point       pnLoc;      /* pen location */
      Point       pnSize;     /* pen size */
      short       pnMode;     /* pattern mode */
      Pattern     pnPat;      /* pen pattern */
      short       pnVis;      /* pen visibility */
      short       txFont;     /* font number for text */
      Style       txFace;     /* text's font style */
      char        filler;
      short       txMode;     /* source mode for text */
      short       txSize;     /* font size for text */
      Fixed       spExtra;    /* extra space */
      long        fgColor;    /* foreground color */
      long        bkColor;    /* background color */
      short       colrBit;    /* color bit */
      short       patStretch; /* used internally */
      Handle      picSave;    /* picture being saved, used internally */
      Handle      rgnSave;    /* region being saved, used internally */
      Handle      polySave;   /* polygon being saved, used internally */
      QDProcsPtr  grafProcs;  /* low-level drawing routines */
   };
typedef struct GrafPort GrafPort;
typedef GrafPort *GrafPtr;
typedef GrafPtr WindowPtr;

Functions

Initializing QuickDraw

pascal void InitGraf            (void *globalPtr);

Opening and Closing Basic Graphics Ports

pascal void OpenPort            (GrafPtr port);
pascal void InitPort            (GrafPtr port); 
pascal void ClosePort           (GrafPtr port);

Saving and Restoring Graphics Ports

pascal void GetPort             (GrafPtr *port);
pascal void SetPort             (GrafPtr port);

Managing Bitmaps, Port Rectangles, and Clipping Regions

pascal void ScrollRect          (const Rect *r, short dh, short dv, 
                                 RgnHandle updateRgn);
pascal void SetOrigin           (short h, short v);
pascal void PortSize            (short width, short height);
pascal void MovePortTo          (short leftGlobal, short topGlobal);
pascal void GetClip             (RgnHandle rgn);
pascal void SetClip             (RgnHandle rgn);
pascal void ClipRect            (const Rect *r);
pascal OSErr BitMapToRegion     (RgnHandle region, const BitMap *bMap); 
pascal void SetPortBits         (const BitMap *bm);

Manipulating Points in Graphics Ports

pascal void GlobalToLocal       (Point *pt);
pascal void LocalToGlobal       (Point *pt);
pascal void AddPt               (Point src, Point *dst);
pascal void SubPt               (Point src, Point *dst);
pascal long DeltaPoint          (Point ptA, Point ptB);
pascal void SetPt               (Point *pt, short h, short v);
pascal Boolean EqualPt          (Point pt1, Point pt2);
pascal Boolean GetPixel         (short h, short v);

Assembly-Language Summary

Data Structures

Point Data Structure
0 v word vertical coordinate
2 h word horizontal coordinate

Rectangle Data Structure
0 topLeft long upper-left corner of rectangle
4 botRight long lower-right corner of rectangle
0 top word upper boundary of rectangle
2 left word left boundary of rectangle
4 bottom word lower boundary of rectangle
6 right word right boundary of rectangle

Region Data Structure
0 rgnSize word size in bytes
2 rgnBBox 8 bytes enclosing rectangle
10 rgnData array region data

Bitmap Data Structure
0 baseAddr long pointer to bit image
4 rowBytes word row width
6 bounds 8 bytes boundary rectangle

GrafPort Data Structure
0 device word device-specific information
2 portBits 14 bytes bitmap
16 portBounds 8 bytes boundary rectangle
24 portRect 8 bytes port rectangle
32 visRgn long visible region
36 clipRgn long clipping region
40 bkPat 8 bytes background pattern
48 fillPat 8 bytes fill pattern
56 pnLoc long pen location
60 pnSize long pen size
64 pnMode word pattern mode
66 pnPat 8 bytes pen pattern
74 pnVis word pen visibility
76 txFont word font number for text
78 txFace word text's font style
80 txMode word source mode for text
82 txSize word font size for text
84 spExtra long extra space
88 fgColor long foreground color
92 bkColor long background color
96 colrBit word color bit
98 patStretch word used internally
100 picSave long picture being saved, used internally
104 rgnSave long region being saved, used internally
108 polySave long polygon being saved, used internally
112 grafProcs long low-level drawing routines

Global Variables
arrow The standard arrow cursor.
black An all-black pattern.
dkGray A 75% gray pattern.
gray A 50% gray pattern.
ltGray A 25% gray pattern.
randSeed Where the random sequence begins.
screenBits The main screen.
thePort The current graphics port.
white An all-white pattern.

Result Codes
pixmapTooDeepErr -148 Pixel map is deeper than 1 bit per pixel
rgnTooBigErr -500 Bitmap would convert to a region greater than 64 KB

0	topLeft	long	upper-left corner of rectangle
4	botRight	long	lower-right corner of rectangle
0	top	word	upper boundary of rectangle
2	left	word	left boundary of rectangle
4	bottom	word	lower boundary of rectangle
6	right	word	right boundary of rectangle

0	rgnSize	word	size in bytes
2	rgnBBox	8 bytes	enclosing rectangle
10	rgnData	array	region data

0	baseAddr	long	pointer to bit image
4	rowBytes	word	row width
6	bounds	8 bytes	boundary rectangle

0	device	word	device-specific information
2	portBits	14 bytes	bitmap
16	portBounds	8 bytes	boundary rectangle
24	portRect	8 bytes	port rectangle
32	visRgn	long	visible region
36	clipRgn	long	clipping region
40	bkPat	8 bytes	background pattern
48	fillPat	8 bytes	fill pattern
56	pnLoc	long	pen location
60	pnSize	long	pen size
64	pnMode	word	pattern mode
66	pnPat	8 bytes	pen pattern
74	pnVis	word	pen visibility
76	txFont	word	font number for text
78	txFace	word	text's font style
80	txMode	word	source mode for text
82	txSize	word	font size for text
84	spExtra	long	extra space
88	fgColor	long	foreground color
92	bkColor	long	background color
96	colrBit	word	color bit
98	patStretch	word	used internally
100	picSave	long	picture being saved, used internally
104	rgnSave	long	region being saved, used internally
108	polySave	long	polygon being saved, used internally
112	grafProcs	long	low-level drawing routines

arrow	The standard arrow cursor.
black	An all-black pattern.
dkGray	A 75% gray pattern.
gray	A 50% gray pattern.
ltGray	A 25% gray pattern.
randSeed	Where the random sequence begins.
screenBits	The main screen.
thePort	The current graphics port.
white	An all-white pattern.

pixmapTooDeepErr	-148	Pixel map is deeper than 1 bit per pixel
rgnTooBigErr	-500	Bitmap would convert to a region greater than 64 KB

Summary of Basic QuickDraw

Pascal Summary

Data Types

Routines

Initializing QuickDraw

Opening and Closing Basic Graphics Ports

Saving and Restoring Graphics Ports

Managing Bitmaps, Port Rectangles, and Clipping Regions

Manipulating Points in Graphics Ports

C Summary

Data Types

Functions

Initializing QuickDraw

Opening and Closing Basic Graphics Ports

Saving and Restoring Graphics Ports

Managing Bitmaps, Port Rectangles, and Clipping Regions

Manipulating Points in Graphics Ports

Assembly-Language Summary

Data Structures

Point Data Structure 0vwordvertical coordinate 2hwordhorizontal coordinate

Rectangle Data Structure 0topLeftlongupper-left corner of rectangle 4botRightlonglower-right corner of rectangle 0topwordupper boundary of rectangle 2leftwordleft boundary of rectangle 4bottomwordlower boundary of rectangle 6rightwordright boundary of rectangle

Region Data Structure 0rgnSizewordsize in bytes 2rgnBBox8 bytesenclosing rectangle 10rgnDataarrayregion data

Bitmap Data Structure 0baseAddrlongpointer to bit image 4rowByteswordrow width 6bounds8 bytesboundary rectangle

Global Variables arrowThe standard arrow cursor. blackAn all-black pattern. dkGrayA 75% gray pattern. grayA 50% gray pattern. ltGrayA 25% gray pattern. randSeedWhere the random sequence begins. screenBitsThe main screen. thePortThe current graphics port. whiteAn all-white pattern.

Result Codes pixmapTooDeepErr-148Pixel map is deeper than 1 bit per pixel rgnTooBigErr-500Bitmap would convert to a region greater than 64 KB

Point Data Structure
0 v word vertical coordinate
2 h word horizontal coordinate

Rectangle Data Structure
0 topLeft long upper-left corner of rectangle
4 botRight long lower-right corner of rectangle
0 top word upper boundary of rectangle
2 left word left boundary of rectangle
4 bottom word lower boundary of rectangle
6 right word right boundary of rectangle

Region Data Structure
0 rgnSize word size in bytes
2 rgnBBox 8 bytes enclosing rectangle
10 rgnData array region data

Bitmap Data Structure
0 baseAddr long pointer to bit image
4 rowBytes word row width
6 bounds 8 bytes boundary rectangle

Global Variables
arrow The standard arrow cursor.
black An all-black pattern.
dkGray A 75% gray pattern.
gray A 50% gray pattern.
ltGray A 25% gray pattern.
randSeed Where the random sequence begins.
screenBits The main screen.
thePort The current graphics port.
white An all-white pattern.

Result Codes
pixmapTooDeepErr -148 Pixel map is deeper than 1 bit per pixel
rgnTooBigErr -500 Bitmap would convert to a region greater than 64 KB